home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Pascal Super Library
/
Pascal Super Library (CW International)(1997).bin
/
LISTS
/
LISTS4
/
LISTS40.DOC
< prev
next >
Wrap
Text File
|
1989-06-25
|
23KB
|
656 lines
LISTS version 4.0
The LISTS unit is designed to make work with doubly-linked lists
a whole lot easier. Now, with Objects and version 4.0 of LISTS,
LISTS itself has become a whole lot easier.
Please note: An awful lot of effort has gone into the
development and testing of LISTS. If you use LISTS and like it,
a $15 registration fee is requested. When registered, you will
receive the source code to LISTS via CompuServe's EasyPlex.
Thank you.
Table of Contents
Page
Section One: Interface. . . . . . . . . . . . . . . . . . . . 1
Section Two: ListObj description. . . . . . . . . . . . . . . 2
F_Entry. . . . . . . . . . . . . . . . . . . . . . . . . . 3
L_Entry. . . . . . . . . . . . . . . . . . . . . . . . . . 3
Init . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Delete . . . . . . . . . . . . . . . . . . . . . . . . . . 3
FirstEntry . . . . . . . . . . . . . . . . . . . . . . . . 4
LastEntry. . . . . . . . . . . . . . . . . . . . . . . . . 4
EntryAbs . . . . . . . . . . . . . . . . . . . . . . . . . 5
EntryRel . . . . . . . . . . . . . . . . . . . . . . . . . 5
MoveEntry. . . . . . . . . . . . . . . . . . . . . . . . . 6
Section Three: EntryObj description . . . . . . . . . . . . . 7
P_Entry. . . . . . . . . . . . . . . . . . . . . . . . . . 7
N_Entry. . . . . . . . . . . . . . . . . . . . . . . . . . 7
Add. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Insert . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . 8
NextEntry. . . . . . . . . . . . . . . . . . . . . . . . . 9
PrevEntry. . . . . . . . . . . . . . . . . . . . . . . . . 9
Examples. . . . . . . . . . . . . . . . . . . . . . . . . . 11
Static entries . . . . . . . . . . . . . . . . . . . . . 11
Dynamic entries. . . . . . . . . . . . . . . . . . . . . 12
Hopes . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
LISTS documentation Page 2
Section One: Interface
------------ ---------
The following describes the Interface section of LISTS (the
routines that can be called from another program.) Please note
that there are no Procedures/Functions per se, but objects and
methods instead. This switch from previous versions of LISTS
makes full use of the new capabilities of TP 5.5 and allows for
much greater flexibility in using LISTS.
INTERFACE
Type
EntryPtr = ^EntryObj;
ListObj = Object
F_Entry : EntryPtr;
L_Entry : EntryPtr;
Constructor Init;
Destructor Done; Virtual;
Function FirstEntry:EntryPtr; Virtual;
Function LastEntry:EntryPtr; Virtual;
Function EntryAbs(Num:LongInt):EntryPtr; Virtual;
Function EntryRel(Num:LongInt):EntryPtr; Virtual;
Procedure MoveEntry(Source, Dest:EntryPtr);
Virtual;
End;
EntryObj = Object
P_Entry : EntryPtr;
N_Entry : EntryPtr;
Constructor Add(Var List:ListObj);
Constructor Insert(Var List:ListObj;
Loc:EntryPtr);
Destructor Remove(Var List:ListObj);
Function NextEntry:EntryPtr; Virtual;
Function PrevEntry:EntryPtr; Virtual;
End;
Notice that all the methods are VIRTUAL, thus allowing the
programmer to customize the routines.
LISTS documentation Page 3
Section Two: ListObj Description
------------ -------------------
The ListObj is a data type of Object which include two data
fields (F_Entry and L_Entry, both of which are of type EntryPtr)
and seven methods (Init, the constructor, Delete, the destructor,
FirstEntry, LastEntry, EntryAbs, EntryRel, and MoveEntry). All
the methods are virtual to allow for simple extensions and
modifications.
------------------------------------------------------------
F_Entry : EntryPtr
------------------------------------------------------------
This data field is a pointer to the first entry in the list.
It should never be accessed by the programmer; use the
method FirstEntry instead.
------------------------------------------------------------
L_Entry : EntryPtr
------------------------------------------------------------
This data field is a pointer to the last entry in the list.
It should never be accessed by the programmer; use the
method LastEntry instead.
------------------------------------------------------------
Constructor Init
------------------------------------------------------------
This routine initializes the List for processing by setting
the data fields to NIL and preparing the Virtual Method
Table (VMT).
Init must be called prior to ANY activity for the List.
Example
Var
List : ListObj;
Begin
List.Init;
End.
------------------------------------------------------------
Destructor Delete
------------------------------------------------------------
This routine does nothing but release the memory used by the
Virtual Method Table (VMT).
Example
Var
LISTS documentation Page 4
List : ListObj;
Begin
List.Init;
...
p
List.Delete;
End.
------------------------------------------------------------
Function FirstEntry:EntryPtr
------------------------------------------------------------
This function returns a pointer to the first entry in the
list. Use this method instead of F_Entry.
This function returns NIL if the List has been Initialized
and is empty.
Example
Var
List : ListObj;
FirstEntryInList : EntryObj;
Begin
List.Init;
...
FirstEntryInList:=List.FirstEntry;
End.
------------------------------------------------------------
Function LastEntry:EntryPtr
------------------------------------------------------------
This function returns a pointer to the first entry in the
list. Use this method instead of L_Entry.
This function returns NIL the the List has been Initialized
and is empty.
Example
Var
List : ListObj;
LastEntryInList : EntryObj;
Begin
List.Init;
LISTS documentation Page 5
...
LastEntryInList:=List.LastEntry;
End.
------------------------------------------------------------
Function EntryAbs(N:LongInt):EntryPtr;
------------------------------------------------------------
This function returns a pointer to the Nth entry in the List
starting from the first as number one.
N must be positive. Negative numbers will return the
FirstEntry in the List.
If N exceeds the number of Entries in the List, EntryAbs
returns the LastEntry in the List.
Example
Var
List : ListObj;
TenthEntry : EntryObj;
Begin
List.Init;
...
TenthEntry:=List.EntryAbs(10);
End.
------------------------------------------------------------
Function EntryRel(Loc:EntryPtr; N:LongInt):EntryPtr
------------------------------------------------------------
This function returns a pointer to the Nth entry relative to
Loc.
N may be positive or negative. If the boundaries of the
List are exceeded, a positive N value will return the
LastEntry in the List while a negative N value will return
the FirstEntry in the List
Example
Var
List : ListObj;
TenthFromLast : EntryObj;
Begin
List.Init;
...
LISTS documentation Page 6
TenthFromLast:=List.EntryRel(List.LastEntry, -10);
End.
------------------------------------------------------------
Procedure MoveEntry(Source, Dest:EntryPtr)
------------------------------------------------------------
This procedure moves the Source entry to the location of
immediately preceding Dest. For example,
Var
L : ListObj;
Begin
L.Init;
...
With L Do
MoveEntry(FirstEntry, LastEntry);
End.
will move the FirstEntry in List, L to the next to the last
position in L.
To move Source to the last position in the List, use NIL as
the value for Dest, for example,
Var
L : ListObj;
Begin
L.Init;
...
With L Do
MoveEntry(FirstEntry, NIL);
End.
Now the FirstEntry in the List has been moved to the
LastEntry and there is a new FirstEntry.
MoveEntry performs no range checks of any sort and therefore
it is the programmer's responsibility to ensure that the
arguments to MoveEntry are both of the same list.
LISTS documentation Page 7
Section Three: EntryObj Description
-------------- --------------------
Like the ListObj, all the methods in EntryObj are virtual.
------------------------------------------------------------
P_Entry : EntryObj
------------------------------------------------------------
Data field pointing to the previous entry in the List.
FirstEntry^.P_Entry points to NIL.
Should not be accessed by the programmer, use PrevEntry
instead.
------------------------------------------------------------
N_Entry : EntryObj
------------------------------------------------------------
Data field pointing to the next entry in the List.
LastEntry^.N_Entry points to NIL.
Should not be accessed by the programmer, use NextEntry
instead.
------------------------------------------------------------
Constructor Add(Var List:ListObj);
------------------------------------------------------------
This routine adds EntryObj into List at the end and sets up
its own Virtual Method Table.
If the List is empty, both List.FirstEntry and
List.LastEntry point to the EntryObj.
Example
Type
EntryRec = Object (EntryObj) {The new object is a
descendant from EntryObj,
which is defined in LISTS}
I:Integer;
End;
Var
List : ListObj;
Entry: EntryRec;
Begin
List.Init;
Entry.I:=1;
Entry.Add(List);
End;
LISTS documentation Page 8
------------------------------------------------------------
Constructor Insert(Var List:ListObj; Loc:EntryPtr)
------------------------------------------------------------
Like Add, this routine sets up the Virtual Method Table
(VMT). Insert also inserts EntryObj into List immediately
preceding Loc, if Loc is NIL, EntryObj is added to the end
of List.
No range checking is performed in Insert, it is the
programmer's responsibility to ensure that Loc is in the
same list as List.
Example
Type
EntryRec = Object (EntryObj) {The new object is a
descendant from EntryObj,
which is defined in LISTS}
I:Integer;
End;
Var
List : ListObj;
Entry: EntryRec;
Begin
List.Init;
...
Entry.I:=2;
Entry.Insert(List, List.LastEntry);
End;
------------------------------------------------------------
Destructor Remove(Var List:ListObj)
------------------------------------------------------------
This routine removes EntryObj from List and frees up the
memory required by EntryObj's Virtual Method Table.
Example
Type
EntryRec = Object (EntryObj)
I : Integer;
End;
Var
List : ListObj;
Entries : Array [1..10] of EntryRec;
N : Integer;
Begin
List.Init;
LISTS documentation Page 9
For N:=1 To 10 Do Begin
Entries[N].I:=N;
Entries[N].Add(List);
End;
Entries[5].Remove(List);
End.
At the end of the program, List would look like this:
1 2 3 4 6 7 8 9 10
------------------------------------------------------------
Function NextEntry:EntryPtr
------------------------------------------------------------
This routine returns the entry immediately after EntryObj.
If the EntryObj is the LastEntry in the list, a value of NIL
is returned.
Example
Type
EntryRec = Object (EntryObj)
I : Integer;
End;
Var
List : ListObj;
Entries : Array [1..10] of EntryRec;
N : Integer;
Begin
List.Init;
For N:=1 To 10 Do Begin
Entries[N].I:=N;
Entries[N].Add(List);
End;
Writeln(EntryRec(Entries[5].NextEntry^).I);
End.
This program would output a "6".
------------------------------------------------------------
Function PrevEntry:EntryPtr
------------------------------------------------------------
This routine returns the entry immediately before EntryObj.
If the EntryObj is the FirstEntry in the List, a value of
NIL is returned.
LISTS documentation Page 10
Example
Type
EntryRec = Object (EntryObj)
I : Integer;
End;
Var
List : ListObj;
Entries : Array [1..10] of EntryRec;
N : Integer;
Begin
List.Init;
For N:=1 To 10 Do Begin
Entries[N].I:=N;
Entries[N].Add(List);
End;
Writeln(EntryRec(Entries[5].PrevEntry^).I);
End.
This program would output a "4".
LISTS documentation Page 11
Examples
--------
The following examples will hopefully make the use of LISTS a bit
clearer.
Static Entries
--------------
Occasionally it might be useful to have static entries in a
List, that is to have the entries declared in the VAR
section of the program. The above examples are examples of
static entries.
To make use of static entries, simply define the TYPE of the
entry as an object which is descendant of EntryObj, for
example,
Type
EntryRec = Object (EntryObj) {Descendant from
EntryObj}
Name:String[30];
End;
Then, in the VAR section, declare variables to be of type
EntryRec which then can become part of a List. For example,
Var
Entry1, Entry2, Entry3 : EntryRec;
NameList : ListObj;
P : EntryPtr;
Begin
NameList.Init;
Write('Enter first name:'); Readln(Entry1.Name);
Write('Enter second name:'); Readln(Entry2.Name);
Write('Entry third name:'); Readln(Entry3.Name);
Entry1.Add(NameList);
Entry2.Add(NameList);
Entry3.Add(NameList);
Writeln('The following is the REVERSED list of
names.');
P:=NameList.LastEntry;
While Not (P=nil) Do Begin
Writeln(EntryRec(P^).Name);
P:=P^.PrevEntry;
End;
End.
LISTS documentation Page 12
Dynamic entries
---------------
Infinitely more useful than Static entries are Dynamic
entries. These entries use the heap to store the
information contained in the List.
Below is the above example written to use Dynamic entries.
Notice that in the output section, after displaying the
name, the program removes the Entry from the List and then
removes the Entry from the heap.
Type
EntryRec = Object (EntryObj) {Descendant from
EntryObj}
Name:String[30];
End;
Var
Entry : ^EntryRec;
Name : String[30];
NameList : ListObj;
P : EntryPtr;
Begin
NameList.Init;
Writeln('Enter names, blank line to stop.');
Repeat
Readln(Name);
If Not (Name='') Then Begin
New(Entry, Add(NameList));
Entry^.Name:=Name;
End;
Until Name='';
Writeln('The following is the REVERSED list of
names.');
P:=NameList.LastEntry;
While Not (P=nil) Do Begin
Writeln(EntryRec(P^).Name);
Entry:=P;
P:=P^.PrevEntry;
Dispose(Entry, Remove);
End;
End.
IMPORTANT NOTE:
Due to the nature of LISTS, each Entry into the List must be
descended from EntryObj.
LISTS documentation Page 13
Hopes
-----
I hope you find LISTS both useful and productive. If you have
any questions or comments regarding the program, please address
them to Mark Addleman via CompuServe (CIS number - 72777, 740)
Thank you very much.
